<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Converting Applications to gdk-pixbuf</title>
<meta name="generator" content="DocBook XSL Stylesheets V1.74.0">
<link rel="home" href="index.html" title="The gdk-pixbuf Library">
<link rel="up" href="apa.html" title="Appendix A. Porting applications from Imlib to gdk-pixbuf">
<link rel="prev" href="apas02.html" title="Differences between Imlib and gdk-pixbuf">
<link rel="next" href="license.html" title="Appendix B. License">
<meta name="generator" content="GTK-Doc V1.11 (XML mode)">
<link rel="stylesheet" href="style.css" type="text/css">
<link rel="reference" href="rn01.html" title="API Reference">
<link rel="reference" href="rn02.html" title="Tools Reference">
<link rel="index" href="api-index-full.html" title="Index of all symbols">
<link rel="index" href="api-index-deprecated.html" title="Index of deprecated symbols">
<link rel="index" href="api-index-2-2.html" title="Index of new symbols in 2.2">
<link rel="index" href="api-index-2-4.html" title="Index of new symbols in 2.4">
<link rel="index" href="api-index-2-6.html" title="Index of new symbols in 2.6">
<link rel="index" href="api-index-2-8.html" title="Index of new symbols in 2.8">
<link rel="index" href="api-index-2-10.html" title="Index of new symbols in 2.10">
<link rel="index" href="api-index-2-12.html" title="Index of new symbols in 2.12">
<link rel="index" href="api-index-2-14.html" title="Index of new symbols in 2.14">
<link rel="appendix" href="apa.html" title="Appendix A. Porting applications from Imlib to gdk-pixbuf">
<link rel="appendix" href="license.html" title="Appendix B. License">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="2"><tr valign="middle">
<td><a accesskey="p" href="apas02.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td>
<td><a accesskey="u" href="apa.html"><img src="up.png" width="24" height="24" border="0" alt="Up"></a></td>
<td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"></a></td>
<th width="100%" align="center">The gdk-pixbuf Library</th>
<td><a accesskey="n" href="license.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td>
</tr></table>
<div class="sect1" lang="en">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="id2920971"></a>Converting Applications to <span class="application">gdk-pixbuf</span>
</h2></div></div></div>
<p>
	This sections describes the actual changes you need to make in
	an <span class="application">Imlib</span> program to make it use <span class="application">gdk-pixbuf</span> instead.
      </p>
<div class="sect2" lang="en">
<div class="titlepage"><div><div><h3 class="title">
<a name="id2917194"></a>Image loading and creation</h3></div></div></div>
<p>
	  The <span class="application">gdk-pixbuf</span> library can load image files synchronously
	  (i.e. with a single function call), create images from RGB
	  data in memory, and as a convenience, it can also create
	  images from inline XPM data.
	</p>
<p>
	  To load an image file in a single function call, simply use
	  <code class="function">gdk_pixbuf_new_from_file()</code>.  Note that
	  this will make the program block until the whole file has
	  been read.  This function effectively replaces
	  <code class="function">gdk_imlib_load_image()</code>.
	</p>
<p>
	  If you have RGB data in memory, you can use
	  <code class="function">gdk_pixbuf_new_from_data()</code> to create a
	  pixbuf out of it; this is a replacement for
	  <code class="function">gdk_imlib_create_image_from_data()</code>.
	  <span class="application">gdk-pixbuf</span> does not copy the image data; it is up to you
	  to define the ownership policy by providing a destroy
	  notification function that will be called when the image
	  data needs to be freed.  The function you provide can then
	  free the data or do something else, as appropriate.
	</p>
<p>
	  As a convenience, you can use the
	  <code class="function">gdk_pixbuf_new_from_xpm_data()</code> function
	  to create a pixbuf out of inline XPM data that was compiled
	  into your C program.  This is a replacement for
	  <code class="function">gdk_imlib_create_image_from_xpm_data()</code>.
	</p>
<p>
	  After you have created a pixbuf, you can manipulate it in
	  any way you please and then finally call
	  <code class="function">g_object_unref()</code> when you are done
	  with it.  This can be thought of as a replacement for
	  <code class="function">gdk_imlib_destroy_image()</code> but with much
	  cleaner semantics.
	</p>
</div>
<div class="sect2" lang="en">
<div class="titlepage"><div><div><h3 class="title">
<a name="id2917298"></a>Rendering Images</h3></div></div></div>
<p>
	  Applications that use <span class="application">Imlib</span> must first call
	  <code class="function">gdk_imlib_render()</code> to render the whole
	  image data onto a pixmap that <span class="application">Imlib</span> creates.  Then they
	  must copy that pixmap's data into the final destination for
	  the image.
	</p>
<p>
	  In contrast, <span class="application">gdk-pixbuf</span> provides convenience functions to
	  render arbitrary rectangular regions of an image onto a
	  drawable that your application provides.  You can use
	  <code class="function">gdk_draw_pixbuf()</code> to do this; having
          your application provide the destination drawable and
	  specify an arbitrary region means your application has
          complete control over the way images are rendered.
	</p>
<p>
	  As a convenience, <span class="application">gdk-pixbuf</span> also provides the
	  <code class="function">gdk_pixbuf_render_pixmap_and_mask()</code>
	  function; this will create new pixmap and mask drawables for
	  a whole pixbuf and render the image data onto them.  Only
	  trivially simple applications should find a use for this
	  function, since usually you want finer control of how things
	  are rendered.
	</p>
</div>
<div class="sect2" lang="en">
<div class="titlepage"><div><div><h3 class="title">
<a name="id2928873"></a>Scaling Images</h3></div></div></div>
<p>
	  <span class="application">Imlib</span> lets you render scaled image data at the time you
	  call <code class="function">gdk_imlib_render()</code>.  Again, this
	  unfortunately scales and renders the whole image onto a new
	  pixmap.
	</p>
<p>
	  <span class="application">gdk-pixbuf</span> provides a number of functions that do scaling
	  of arbitrary regions of a source pixbuf onto a destination
	  one.  These functions can also perform compositing
	  operations against the data in the destination pixbuf or
	  against a solid color or a colored checkerboard.
	  <sup>[<a name="id2928910" href="#ftn.id2928910" class="footnote">1</a>]</sup>
	</p>
<p>
	  Very simple applications may find it sufficient to use
	  <code class="function">gdk_pixbuf_scale_simple()</code> or
	  <code class="function">gdk_pixbuf_composite_color_simple()</code>.
	  These functions scale the whole source image at a time and
	  create a new pixbuf with the result.
	</p>
<p>
	  More sophisticated applications will need to use
	  <code class="function">gdk_pixbuf_scale()</code>,
	  <code class="function">gdk_pixbuf_composite()</code>, or
	  <code class="function">gdk_pixbuf_composite_color()</code> instead.
	  These functions let you scale and composite an arbitrary
	  region of the source pixbuf onto a destination pixbuf that
	  you provide.
	</p>
</div>
<div class="sect2" lang="en">
<div class="titlepage"><div><div><h3 class="title">
<a name="id2928975"></a>Getting Image Data from a Drawable</h3></div></div></div>
<p>
	  <span class="application">Imlib</span> lets you create an image by fetching a drawable's
	  contents from the X server and converting those into RGB
	  data.  This is done with the
	  <code class="function">gdk_imlib_create_image_from_drawable()</code>
	  function.
	</p>
<p>
	  <span class="application">gdk-pixbuf</span> provides the
	  <code class="function">gdk_pixbuf_get_from_drawable()</code> function
	  instead.  It lets you specify a destination pixbuf instead
	  of always creating a new one for you.
	</p>
</div>
<div class="footnotes">
<br><hr width="100" align="left">
<div class="footnote">
<p><sup>[<a name="ftn.id2928910" href="#id2928910" class="para">1</a>] </sup>
	      You can use a colored checkerboard as the background for
	      compositing when you want to provide a visual indication
	      that the image has partially opaque areas.  This is
	      normally used in image editing and viewing programs.
	    </p>
<p>
	      Compositing against a single solid color is actually a
	      special case of a checkerboard; it simply uses checks of
	      the same color.
	    </p>
</div>
</div>
</div>
<div class="footer">
<hr>
          Generated by GTK-Doc V1.11</div>
</body>
</html>
